Messier 051

Montage is a general astronomical image toolkit with facilities for reprojection, background matching, coaddition and visualization. It can be used as a set of command-line tools (Linux, OS X and Windows), C library calls (Linux and OS X) and as Python binary extension modules.

Montage source code can be downloaded from GitHub ( https://github.com/Caltech-IPAC/Montage ). The Python package can be installed from PyPI ("pip install MontagePy"). See http://montage.ipac.caltech.edu/ for more information.

MontagePy.main modules: mAdd

A large percentage of the Montage modules focus on processing a set of images (often retrieved from a mission archive); projecting them to a common frame, adjusting their background levels as a set, and coadding them into a mosaic.

Starting with archive access, this mosaicking sequence uses the following modules:

  • mHdr — Make a template FITS header for a region.
  • mArchiveList — Identify archive images for a region.
  • mArchiveGet and mArchiveExec — Retreive archive images individually or as a set.
  • mImgtbl — Mine a set of images for metadata (and in particular sky coverage).
  • mCoverageCheck — Subset an image list based on a region specification.
  • mMakeHdr or mHdr — Make a template FITS header bounding a set of images or the header for a sky region.
  • mProject / mProjectPP / mProjectQL and mProjExec — Reproject images individually or as a set.
  • mOverlaps — Determine which images in a set overlap each other.
  • mDiff/mFitplane and mDiffFitExec — Fit the differences between images one pair at a time or all the differences.
  • mBgModel — Model a set of differences to determine the "best" background correction for each image.
  • mBackground and mBgExec — Background-correct an image or a set of images.
  • mAdd — Coadd reprojected (and background corrected) images into a final mosaic.

This page is focused on the details of one of these modules: mAdd. For a broader context, please see Building a Mosaic with Montage or the one shot version if you just want to see the commands.

Note: The MontagePy python package has no external dependencies. We include other utilities on this page to aid in visualizing MontagePy package results.

In [1]:
from MontagePy.main import mAdd, mViewer

help(mAdd)

Help on built-in function mAdd in module MontagePy.main:

mAdd(...)
    mAdd coadds as set of images that have been reprojected to the same pixel framework into a final mosaic.
    
    Parameters
    ----------
    path : str
        Directory containing files to be coadded.
    tblfile : str
        Table file list of reprojected files to coadded.
    template_file : str
        FITS header file used to define the desired output.
    outfile : str
        Final mosaic FITS file.
    shrink : bool, optional
        Shrink-wrap to remove blank border areas.
    haveAreas : bool, optional
        Area files exist for weighting the coadd.
    coadd : int, optional
        Image stacking: 0(MEAN), 1(MEDIAN), 2(COUNT).
    debug : int, optional
        Debugging output level.
    
    
    Returns
    -------
    status : int
        Return status (0: OK, 1:ERROR).
    msg : str
        Return message (for errors).
    time : float
        Total processing time (sec).

mAdd Example

mAdd is the tail end of the mosaicking process. At this point we have a set of reprojected (and often background-matched) images and have generated a metadata table listing them all. The last step is to coadded them all, properly weighting things like fractional pixels, to produce the final mosaic.

The basic inputs are the images themselves (the path to them and the table of metadata), the header template for the output (which by now should match, except for integer pixel offsets, the headers in each image), and the name of the desired output image file.

mAdd has a few extra controls that can be used to tell it whether to "shrink-wrap" the mosaic (remove empty border pixel areas) and whether the input images have associated "area" images (for proper weighting of fractional pixel coaddition). In addition, the user has the option of overriding the default coaddition mode (mean) and instead return the median or just the count of the input pixels.

See previous steps in the process for details on the header template.

In [3]:
rtn = mAdd("M17/corrected", "M17/cimages.tbl", "M17/M17.hdr", "work/M17/mosaic.fits")

print(rtn)

{'status': '0', 'time': 1.0}

 

Here is one of the input (reprojected, background-matched) images:

In [5]:
from IPython.display import Image

rtn = mViewer('-ct 1 -gray M17/corrected/hdu0_2mass-atlas-990502s-j1430080.fits \
              -2s max gaussian-log -out work/M17/hdu0_2mass-atlas-990502s-j1430080_add.png',
              '', mode=2)

print(rtn)

Image(filename='work/M17/hdu0_2mass-atlas-990502s-j1430080_add.png')

{'status': '0', 'type': b'grayscale', 'nx': 513, 'ny': 1024, 'grayminval': 146.26332325927484, 'grayminpercent': 0.0, 'grayminsigma': -2.0, 'graymaxval': 10006.5115462375, 'graymaxpercent': 100.0, 'graymaxsigma': 1334.2638415582198, 'blueminval': 0.0, 'blueminpercent': 0.0, 'blueminsigma': 0.0, 'bluemaxval': 0.0, 'bluemaxpercent': 0.0, 'bluemaxsigma': 0.0, 'greenminval': 0.0, 'greenminpercent': 0.0, 'greenminsigma': 0.0, 'greenmaxval': 0.0, 'greenmaxpercent': 0.0, 'greenmaxsigma': 0.0, 'redminval': 0.0, 'redminpercent': 0.0, 'redminsigma': 0.0, 'redmaxval': 0.0, 'redmaxpercent': 0.0, 'redmaxsigma': 0.0, 'graydatamin': 152.41320609320312, 'graydatamax': 10006.5115462375, 'bdatamin': 0.0, 'bdatamax': 0.0, 'gdatamin': 0.0, 'gdatamax': 0.0, 'rdatamin': 0.0, 'rdatamax': 0.0, 'flipX': 0, 'flipY': 1, 'colortable': 1, 'bunit': b''}
Out[5]:

 

and here is the mosaic (the above image contains the eastern part of the nebulosity):

In [6]:
rtn = mViewer('-color black -imginfo M17/rimages.tbl \
              -ct 1 -gray M17/mosaic.fits -2s max gaussian-log \
              -out work/M17/mosaic_add.png',
              '', mode=2)

print(rtn)

Image(filename='work/M17/mosaic_add.png')

{'status': '0', 'type': b'grayscale', 'nx': 3601, 'ny': 3600, 'grayminval': 149.5791825248529, 'grayminpercent': 0.0, 'grayminsigma': -2.0, 'graymaxval': 10639.0999189825, 'graymaxpercent': 100.0, 'graymaxsigma': 2240.4651757359084, 'blueminval': 0.0, 'blueminpercent': 0.0, 'blueminsigma': 0.0, 'bluemaxval': 0.0, 'bluemaxpercent': 0.0, 'bluemaxsigma': 0.0, 'greenminval': 0.0, 'greenminpercent': 0.0, 'greenminsigma': 0.0, 'greenmaxval': 0.0, 'greenmaxpercent': 0.0, 'greenmaxsigma': 0.0, 'redminval': 0.0, 'redminpercent': 0.0, 'redminsigma': 0.0, 'redmaxval': 0.0, 'redmaxpercent': 0.0, 'redmaxsigma': 0.0, 'graydatamin': 150.8148507701094, 'graydatamax': 10639.0999189825, 'bdatamin': 0.0, 'bdatamax': 0.0, 'gdatamin': 0.0, 'gdatamax': 0.0, 'rdatamin': 0.0, 'rdatamax': 0.0, 'flipX': 0, 'flipY': 1, 'colortable': 1, 'bunit': b''}
Out[6]:

mAdd Error Handling

If mAdd encounters an error, the return structure will just have two elements: a status of 1 ("error") and a message string that tries to diagnose the reason for the error.

For instance, if the user asks for a table that doesn't exist:

In [7]:
rtn = mAdd("M17/corrected", "M17/unknown.tbl", "M17/M17.hdr", "work/M17/mosaic.fits")

print(rtn)

{'status': '1', 'msg': b'Invalid image metadata file: M17/unknown.tbl'}

 

Classic Montage: mAdd as a Stand-Alone Program

mAdd Unix/Windows Command-line Arguments

mAdd can also be run as a command-line tool in Linux, OS X, and Windows:

Usage: mAdd [-d level] [-p imgdir] [-n(o-areas)] [-a mean|median|count] [-e(xact-size)] [-s statusfile] images.tbl template.hdr out.fits

 

mAdd as a Library Call

If you are writing in C/C++, mAdd can be accessed as a library function:

/*-***********************************************************************/
/*                                                                       */
/*  mAdd                                                                 */
/*                                                                       */
/*  Montage is a set of general reprojection / coordinate-transform /    */
/*  mosaicking programs.  Any number of input images can be merged into  */
/*  an output FITS file.  The attributes of the input are read from the  */
/*  input files; the attributes of the output are read a combination of  */
/*  the command line and a FITS header template file.                    */
/*                                                                       */
/*  This module, mAdd, reads sets of flux / area coverage images         */
/*  (the output of mProject) which have already been projected /         */
/*  resampled onto the same pixel space.  The fluxs, scaled by total     */
/*  input area, are then coadded into a single output composite.         */
/*                                                                       */
/*   char  *path           Directory containing files to be coadded      */
/*   char  *tblfile        Table file list of reprojected files to       */
/*                         coadd                                         */
/*   char  *template_file  FITS header file used to define the desired   */
/*                         output                                        */
/*   char  *outfile        Final mosaic FITS file                        */
/*                                                                       */
/*   int    shrink         Shrink-wrap to remove blank border areas      */
/*   int    haveAreas      Area files exist for weighting the coadd      */
/*   int    coadd          Image stacking: 0 (MEAN), 1 (MEDIAN)          */
/*                         2 (COUNT), 3 (SUM)                            */
/*                                                                       */
/*   int    debug          Debugging output level                        */
/*                                                                       */
/*************************************************************************/


struct mAddReturn *mAdd(char *path, char *tblfile, char *template_file, char *outfile,
                        int shrink, int haveAreas, int coadd, int debugin)

Return Structure

struct mAddReturn
{
   int    status;        // Return status (0: OK, 1:ERROR)
   char   msg [1024];    // Return message (for error return)
   char   json[4096];    // Return parameters as JSON string
   double time;          // Run time (sec)   
};